<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="Build">
   <meta name="GENERATOR" content="Mozilla/4.5 [en] (Win98; I) [Netscape]">
   <title>Validate Edit/Save</title>
</head>
<body>

<h1>
Eclipse Platform<br>
Core Support for Validate Edit/Save</h1>
Last revised 11:03 EST Thursday December 6 2001
<p>This proposal describes a Platform Core mechanism that allows clients
to trigger VCM involvement in Core operations that change the content of
file resources in the workspace. The mechanism is done in such a way that
the client requires no direct knowledge on the VCM component, or even of
its existence. This permits client code to work in a uniform way in all
configurations.
<p>There are two parts to the mechanism:
<ul>
<li>
<b>Validate-edit</b> - Explicitly activated by clients who expect&nbsp;
to modify a file and would like to "tickle" the VCM component so that it
has an opportunity to ask the user whether they would like to check out
the file (or something along those lines). A typical text editor might
invoke this mechanism the first time the user dirties an editor buffer
that the user has opened on a file that is read-only.</li>

<li>
<b>Validate-save</b> - Implicitly activated by clients as they modify the
contents of a file resource on disk. This hook provides a final opportunity
for the VCM component to check out a file that is about to be written without
prior approval/check-out.</li>
</ul>
An internal prototype of the validate-save mechanism was included in Eclipse
1.0. This proposal improves and extends that early effort, and makes it
public API in the Core resources plug-in.
<h3>
Core API for regular workspace clients</h3>
The validate-save hook is hidden in the internal implementation of IFile.
The affected methods are setContents and appendContents. Note that this
hook does not apply to the operations that create new files (create, copy,
move); it only affects existing files whose contents are to be modified.
<p>In both methods, the hook is activated in the method preamble before
the method does any real work. The hook is activated unconditionally on
each invocation as long as a party (i.e., the VCM component) has registered
a validator. The hook method returns a status code so that it can veto
the operation and provide a reason that could be presented to the user.
If the veto is exercised, the client will be unable to modify the contents
of the file.
<p>The preamble looks like:
<p>if there is a registered validator then
<br>&nbsp;&nbsp;&nbsp; call validator.validateSave passing this file
<br>&nbsp;&nbsp;&nbsp; if the returned status is not OK then
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; throw a core exception with
the given status (after closing the given input stream)
<p>The hook implementation runs headless, and should not invoke UI operations
on pain of deadlock.
<p>The API specifications of IFile.appendContents and both IFile.setContents
methods would be changed to add a note to the effect that these method
invoke IFileModificationValidator the registered via the org.eclipse.core.resources.fileModificationValidator
extension point.
<p>The validate-edit mechanism would be exposed in the IWorkspace API interface
so that a client can trigger it explicitly:
<p><font face="MS Sans Serif">public IStatus validateEdit(IFile[] files,
Object context);</font>
<p>This operation allows a client to declare its intent to modify all of
the given files and ask for permission to proceed. The files must all exist
in the workspace. The mechanism allows the VCM component to provide the
implementation of this method; a typical behavior would be to check out
any files that haven't already been checked out. The context passed in is a
SWT shell used to parent any windows that the implementation may need to
bring up to interact with the user; if no context is supplied (null is
passed in), the validation must be done in a headless manner. A returned
status of OK indicates to the client that it may proceed; other returned
statuses indicate the reason why the individual files cannot be modified.
When a UI context is supplied, the caller should assume that the user has
been informed of the problems; if no UI context is passed, the caller may
describe the problem to the user by displaying the returned status. Note
that this operation should not change resources in the workspace.
<p>Threading-wise, if this method is invoked from the UI thread and passed
a shell, there should be no problem (even if the workspace lock is held).
However, if the caller is not in the UI thread and passes a shell, you
will get deep trouble if you are holding the workspace lock - because the
UI brought up by the validation will be in the UI thread and will deadlock
if it tries if do any workspace modification operations of its own.
<h3>
Core API for the client implementing the hook</h3>
The following API interface would be added to the Core resources API. This
interface would be implemented by the VCM component.
<p><font face="MS Sans Serif">public interface <tt>IFileModificationValidator
</tt>{</font>
<br><font face="MS Sans Serif">&nbsp;&nbsp;&nbsp; public IStatus validateSave(IFile
file);</font>
<br><font face="MS Sans Serif">&nbsp;&nbsp;&nbsp; public IStatus validateEdit(IFile[]
files, Object context);</font>
<br><font face="MS Sans Serif">}</font>
<h3>
Core Resources extension point</h3>
The Core resources plug-in would provide a new extension point, called
fileModificationValidator, intended to be extended by none other than the
VCM component.
<br><b><i>Identifier: </i></b>org.eclipse.core.resources.fileModificationValidator
<p><b><i>Description:</i></b> For providing an implementation of an IFileModificationValidator
to be used in the validate-edit and validate-save mechanism. This extension
point tolerates at most one extension.
<p><b><i>Configuration Markup:</i></b>
<p><tt>&nbsp;&nbsp; &lt;!ELEMENT fileModificationValidator EMPTY></tt>
<br><tt>&nbsp;&nbsp; &lt;!ATTLIST fileModificationValidator class CDATA
#REQUIRED></tt>
<ul>
<li>
<b>class</b> - a fully qualified name of a class which implements <tt>org.eclipse.core.resource.IFileModificationValidator</tt>.</li>
</ul>
<b><i>Examples:</i></b>
<p>The following is an example of using the <tt>fileModificationValidator
</tt>extension point.
<p>(in file <tt>plugin.xml</tt>)
<p><tt>&nbsp;&nbsp; &lt;extension point="org.eclipse.core.resources.fileModificationValidator"></tt>
<br><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;fileModificationValidator class="com.xyz.vcm.VCMFileModificationValidator"/></tt>
<br><tt>&nbsp;&nbsp; &lt;/extension></tt>
<h3>
API Compatibility</h3>
In summary, the changes affect the Eclipse Platform Core component API
in the following ways:
<ul>
<li>
Adding a new API method to IWorkspace.</li>

<li>
Changing the contract of 3 existing API methods (IFile.appendContents and
two IFile.setContents) in a compatible way.</li>

<li>
Adding a new extension point.</li>

<li>
Adding a new API interface to go with the new extension point.</li>
</ul>
The changes maintain full API compatibility with existing plug-ins in compliance
with the 1.0 API.
</body>
</html>
